SAM to SAPI 4 interface Driver

This file is best read in a text editor with wordwrap turned on.

This is a fully functional SAM driver for use with synthesisers supporting the Microsoft Speech API (SAPI) standard. There is a wide range of SAPI synthesisers available and most of these are software synthesisers (that is, they do not use any special external hardware but use the computer's soundcard for speech output).

Please report any bugs to Dolphin. If it crashes please tell us the crash address (and the name of the DLL) and registers etc, from the crash message box, also report the driver version number (check with explorer - file properties). Please also tell us the SAPI synthesiser you were using and its version.

Please note: the success of the SAM to SAPI interface driver can depend on the quality and reliability of the SAPI synthesiser you are using.

Features
Automatic detection of synthesisers.
Supports volume, speed and pitch commands.
Driver information panel will give you all engine info.
Indexing can be to the nearest character.
Prompts are translatable. UK and US prompts are built in, others can be read from a prompt file.

Restrictions 
No language switching capability.
Additional commands supported by some synthesisers are not available.


Using the SAM to SAPI driver

Generally, this driver will behave as any ordinary SAM driver and you will be able to use your SAPI synthesiser just as any other synth.

However, you may wish to configure this driver for optimal performance.

To select which SAPI synthesiser you wish to use:

1. Go into the driver information panel (for example, from the SAM Control Panel, select the SAM to SAPI driver and choose Configure).

2. From the Engine list, select which SAPI Engine to use. Engines correspond to unique synthesisers.

3. Tab to the Mode list and select a mode to use. Modes define the voice characteristics and language of your synth.

4. The About, General, Lexicon and Translation buttons provide access to the configuration dialog boxes of the selected synthesiser. Not every engine may support every dialog.

5. Choose OK to confirm your selection.

Then, to use the SAPI synth, select the SAM to SAPI driver from the list of available synthesisers in your access product.

You may find that when you first use your SAPI synth, certain characters are not announced. This is because not all SAPI synthesisers can speak all characters. In order to fix this problem, you need to tell the driver about the characters the synthesiser has trouble with. This information is stored in the file STS.INI (in the same folder as the SAM to SAPI driver, probably c:\program files\sam\samsapi\sts.ini, or in the SAMSAPI folder of wherever you installed SAM).

When you use a SAPI synthesiser with this driver for the first time, the driver creates a section for your synthesiser in the file STS.INI. However, it is left blank for you to fill in.

Information held in the STS.INI file is the set of characters which can be spoken by the synthesiser along with special information about characters which require handling by the driver.

You can have this information apply to just the mode of the SAPI synthesiser (mode specific), or to any mode in the synthesiser (Engine specific), or to any synthesiser using that language (Language specific).

To edit the information held in STS.INI:

1. Load the file STS.INI into an ordinary text editor (Notepad will do).

2. Locate the section of the file to be altered, this will be indicated by a line such as the following:
; Engine: Microsoft TTS Engine, Mode: Mary

Immediately after this line will be a line like the following:
[{C77C5170-2867-11D0-847B-444553540000}]

Your configuration entries should follow this second line.

3. A typical configuration section looks like the following:
text="..."
mod="..."
spell="..."
spellreplace0="..."
spellreplace1="..."
...

The line text="..." lists all the characters which can be used to form words. This should include letters and any accented characters used. Numbers should also be included in this line.

For example:
text="0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"

You can also specify ranges of characters with the range marker (-), so the previous line of characters could be written:

text="0-9A-Za-z"

Any characters outside the standard ANSI range should be entered as Unicode values. For example, a capital Greek Alpha should be entered as \0391. All values are represented by four digit hexadecimal numbers.

The range marker can also be used with unicode values. For example, if you wanted to include the whole range of CJK ideographic characters:

text="0-9A-Za-z\4e00-\9fff"

The mod="..." line lists the modifier characters. Modifiers do not produce any sound by themselves, but affect the way text is read. For example, a full stop causes the voice to go down. A typical line could be:
mod=" !',.:;?"

The spell="..." line lists all other punctuation characters. For example:
spell="\0022#$%&()*+\002d/<=>@[\005c]^_`{|}~"

Notice here that the double quote mark (") is entered as \0022 and the backslash character is entered as \005c. A dash (-) has to be entered as
\002d to avoid it from being used as a range marker.

The spellreplace lines list any characters which the synthesiser may not always announce consistently. For example, this will always include the space character. It may also include the backslash and any other punctuation marks which the synthesiser may sometimes not speak.

Each spellreplace entry is entered as follows:

spellreplace<n>="<char><spelling>"

where:
<n> is a number (starting from 0),
<char> is the character the synthesiser has trouble with,
<spelling> is a spelling replacement for the character.

For example, assume a synthesiser could not speak the space, full stop, question mark or backslash. We would have lines such as:
spellreplace0=" SPACE"
spellreplace1=".DOT"
spellreplace2="?QUESTION"
spellreplace3="\005cBACKSLASH"

4. Once you have made your changes to the STS.INI file, save it and choose the Redetect All button from the SAM Control Panel, or reselect your synthesiser from the list in the SAM to SAPI Driver Information Panel.

5. In addition to the STS.INI file, there are language files STSnnnnn.INI which contain the translated prompts used by the driver (where nnnnn is the five digit language code).

An example of this file is contained in the file STS00044.INI (UK English).

You may wish to edit this file in order to have correct parameter descriptions available.

